从炫技到落地：Agent 工程化上线的 12 条关键经验

来源：htmlDecode("悟鸣AI")

原文链接：https://mp.weixin.qq.com/s/KJVL18P8P6lOYdhiL67yhw

---

大家好，我是悟鸣。
这两年，Agent 圈子里有一种很常见的错觉。
很多系统在演示阶段都特别亮眼，任务一跑，效果惊艳，团队也会很快进入兴奋状态。可一旦真的接进真实业务，问题就开始一个接一个冒出来。今天跑偏，明天失控，后天又因为上下文污染、流程混乱或者经验没有沉淀，变得越来越难维护。
很多人第一反应会把原因归到模型、Prompt 或工具链上。可如果把观察周期拉长一点，你会发现，真正决定一个 Agent 系统能不能长期稳定运行的，往往是背后的工程约束。
最近我看到一套很有启发的方法论，叫  ** 12-Factor AgentOps ** 。
网站地址：https://www.12factoragentops.com/
它讨论的重点，是当 Agent 真的进入生产环境之后，你要靠什么让它持续、稳定、可控地工作。
如果你正在做 AI Coding、Agent 工作流，或者想把一个能跑的原型推进成能上线的系统，这 12 条原则很值得认真过一遍。

这套方法论到底在讲什么

12-Factor AgentOps 的核心判断很简单：一个能长期跑下去的 Agent 系统，必须同时建立三种纪律。 ** 上下文纪律 ** ：控制 Agent 在每一步究竟看到什么，不让它默认吞下全部信息 ** 知识纪律 ** ：把每次会话里的经验提取出来、验证清楚，再回流到后续会话中 ** 流程纪律 ** ：用外部验证、单向推进和层级监督，保证系统质量不会一路滑坡
如果按适用范围来看，这 12 条原则又分成两层。 ** Factor I 到 IX **  更适合单 Agent 场景 ** Factor X 到 XII **  面向多 Agent 并行和编排场景
换句话说，这套方法论真正提醒我们的，是一件很容易被忽略的事：
** Agent 不是一个更聪明的脚本，它本质上是一套需要被治理的生产系统。 **

十二条原则

I. Context Is Everything｜上下文即一切

很多人对上下文窗口有个误解，觉得只要窗口足够大，就可以不断往里塞信息。
现实并不是这样。LLM 并不会像数据库那样稳定记住所有内容。它对开头和结尾通常更敏感，中间信息更容易被忽略。所以，进入上下文窗口的内容，本身就应该被当作一种稀缺资源来管理。
这条原则背后的核心动作有三个。 只在当前步骤加载真正需要的上下文 在阶段切换时主动做压缩，用摘要替代整段原始对话 尽量把上下文利用率控制在窗口上限的 40% 以内
很多 Agent 后面越跑越乱，问题不一定出在能力不够，很可能只是上下文已经失控了。

II. Track Everything in Git｜一切纳入 Git

这里说的“一切”，真的不是一句口号。
除了代码，Issue、决策记录、经验教训、会话产物、Agent 交接笔记，都应该尽量进入 Git。因为 Git 天然提供了版本历史、差异对比、协作能力和审计线索，而且没有额外依赖。
判断这条原则有没有做到位，有一个很直观的标准：
如果一个新 Agent 只靠一次  git clone ，就能把项目的工作上下文基本恢复出来，那你的系统就已经足够健康了。
反过来看，如果状态散落在 Jira、Notion、聊天记录、向量数据库等多个地方，Agent 每次启动都要重新拼上下文，整个系统的维护成本只会越来越高。

III. One Agent, One Job｜一 Agent 一任务

每个 Agent 都应该只做一件边界清晰的事，并且使用新的上下文窗口。
这一点听起来简单，真正落地时却很容易偷懒。比如一个 Agent 刚做完代码研究，团队往往会顺手让它继续实现。问题在于，这时候它的窗口里已经塞满了研究上下文，继续写实现，反而更容易偏。
更稳妥的做法是，阶段一结束就停下来，把研究结果蒸馏成摘要，再启动新的 Agent 继续往下走。
Worker 级 Agent 只处理单个 Issue，至于批量协调、任务编排和资源分配，应该交给更上层的编排系统。

IV. Research Before You Build｜先研究，再动手

很多返工，问题往往不在写得慢，而在一开始就写偏了。
所以这条原则强调，每次实现之前，都应该先有一个独立的研究阶段。跳过研究，Agent 很容易写出那种看起来没问题、实际上和代码库完全不贴合的代码。它可能重复已有工具，违背既有架构决策，也可能直接撞上项目约定。
研究阶段最理想的产物，是一份结构化的发现文档。后面的实现，应该建立在这份输入之上。
前面多花 10 分钟研究，后面往往能少掉几小时返工。这个账其实很划算。

V. Validate Externally｜外部验证

Agent 不能自己验证自己，这件事最好在系统层面写死。
同一个上下文里生成了代码，再让同一个上下文回头审查这段代码，本质上还是在放大确认偏误。真正有效的验证，必须来自外部。
这个“外部”可以是不同 Agent、不同模型、自动化测试套件，或者人类专家。安全、架构、法律这类高风险决策，更应该明确保留人工介入。
测试之所以重要，是因为它不关心你的主观意图，只关心最终行为是不是满足断言。对 Agent 来说，这种验证方式最干净，也最不讲情面。

VI. Lock Progress Forward｜让进度只能向前

通过验证的工作，应该被锁住，不能随意退回去。
这里讲的是一种棘轮机制。Agent 可以在前面阶段自由探索，也可以并行尝试不同方案，但只有那些已经通过验证的结果，才能进入主线。
受保护的主分支、Issue 状态锁、完成账本，这些东西合在一起，才能把系统变成单向推进的结构。
同时还要给失败设置预算。达到上限之后，就应该升级处理，而不是让 Agent 一直在原地打转。
Agent 的试错成本其实不高，真正昂贵的是人的时间。棘轮机制的意义，就是把混乱搜索变成有效推进。

VII. Extract Learnings｜提取经验

一次会话结束后，留下来的不该只有工作产物，还应该有经验教训。
很多团队只盯着结果文件，却默认让过程里的判断、失败和坑点随着会话一起消失。这样做的代价，就是同样的问题会被反复踩。
值得提取的东西包括这些。 做了什么决策，为什么这样做 哪些方法试过了，但行不通 过程中识别出了什么模式 集成时踩到了哪些坑
经验一定要结构化、可打标签、可搜索。只要这一步能做好，短短几分钟的整理，后面往往能省下几小时重复劳动。

VIII. Compound Knowledge｜让知识产生复利

提取经验只是第一步，更关键的是把它重新送回系统里。
12-Factor AgentOps 提到一个很重要的闭环：提取、质量门控、存储、会话启动时注入、引用追踪与衰减。
也就是说，经验不能只是被存下来，它还要在下一轮任务启动时真正被用上。如果只是放进仓库里，从来没有被引用，那它就还没有形成组织能力。
原文里给了一个很有意思的判断式：
检索率 × 引用率 > 衰减率
只要这个关系成立，后面的会话质量就会逐步高于前面的会话。长期来看，这种组织记忆，才是一个团队最难被复制的部分。
模型会升级，框架会变化，API 也会换代，但真正能持续复利的，始终是团队沉淀下来的经验体系。

IX. Measure What Matters｜度量真正重要的东西

很多团队一做 Agent，就很容易掉进“看起来很忙”的指标陷阱。
比如 Token 消耗、会话数量、代码行数、关闭的 Issue 数，这些数据当然能看，但它们更像活跃度，不等于系统真的在逼近目标。
真正值得持续追踪的，应该是这些指标。 目标完成率 单目标成本 知识引用率 人工干预频率 同类故障复发率
这里还有一个我很喜欢的判断： ** 休眠本身就是成功。 **
如果目标已经达成，系统也没有继续制造任务，那说明系统在健康地完成工作。为了把指标做高，反过来制造更多动作，这恰恰说明运维约束出了问题。

X. Isolate Workers｜隔离 Worker

到了多 Agent 场景，隔离就变得更重要了。
每个 Worker 都应该有自己独立的 Git Worktree、独立的上下文窗口，以及尽量接近零共享的可变状态。
一旦共享工作目录，就容易出现竞态条件；一旦共享上下文窗口，就容易出现隐性耦合。这两种问题都特别难排查，而且很容易引发连锁故障。
隔离的代价，其实只是多一些磁盘空间和 Token 消耗。可换来的，是干净的恢复能力、更低的交叉污染，以及更线性的扩展空间。
磁盘很便宜，排错时间很贵。这笔账其实很好算。

XI. Supervise Hierarchically｜层级监督

多 Agent 系统不能靠“大家互相商量着来”维持秩序。
更合理的方式，是建立一棵监督树。每个 Agent 只有一个上级，问题升级只能向上流动，不能横向扩散。Worker 在本地做有限次重试之后，把问题升级给 Supervisor；Supervisor 再决定是重新分配、重新定义，还是继续向上升级。
这样做的好处，是人类不需要被塞进每一次小重试循环里。最终送到人面前的，应该是已经带着上下文、优先级和整理结果的升级请求。
这里设置层级，是为了给错误处理留出一条明确路径。

XII. Harvest Failures as Wisdom｜把失败也变成系统能力

很多团队会记录成功经验，却不认真处理失败。
但从系统进化的角度看，失败尝试本身就是高价值数据。它值得被提取、归档和索引，而且严谨程度不应该低于成功案例。
如果一个 Agent 前面试了三种方法都失败，第四种才成功，那么真正有价值的，不只是最后那个成功方案，还有前面那三条“在什么条件下行不通”的负知识。
很多时候，负知识比正知识更有用。因为它可以直接帮系统剪掉无效搜索空间。
所以，除了看成功率，也要持续看故障率有没有下降。如果失败一直在重复出现，那就说明这些失败还没有真正变成系统能力。

最后想说的

如果让我把这 12 条原则压缩成一句话，我会这么说：
** 真正拉开 Agent 系统差距的，是它出问题之后，整套系统还能不能稳住。 **
这也是我最认同 12-Factor AgentOps 的地方。它没有把重点放在“怎么把 Agent 做得更像人”，而是把注意力放回到了更现实的层面：怎么把 Agent 当成生产系统去治理。
如果你准备开始真正落地，我会特别建议先从三件事做起。 先把上下文收紧，别让 Agent 背着整个项目到处跑。 把验证外置，别让同一个 Agent 自己写、自己审、自己给自己打分。 把经验沉淀下来，尤其是失败经验，因为那往往才是下一轮效率提升的起点。
很多 Agent 项目最后做不下去，往往都卡在系统缺少约束。
所以从这个角度看，12-Factor AgentOps 值得每个做 Agent 的团队认真读一遍。它讲的是一整套能让系统真正跑起来的工程常识。
大厂 AI 应用工程师、讲师、Qoder 大使、Cherry Studio 认证讲师、慕课网和掘金专栏作者，CSDN、阿里云技术社区等主流博客平台专家博主。